home *** CD-ROM | disk | FTP | other *** search
/ The Mac Mega CD - Killer Software / The Mac Mega CD - Killer Software (May 1996).dmg / Shareware City / Sound / MacMikMod 2.10+src / docs / mloader.doc < prev    next >
Encoding:
Text File  |  1995-11-19  |  6.2 KB  |  201 lines  |  [TEXT/CWIE]
  1. ⁄ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒø
  2. ≥MLOADER.C Module Documentation≥
  3. ¿ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒŸ
  4.  
  5. Date last modified: October 20, 1995
  6.  
  7. MLOADER.C uses 2 routines of the MDRIVER.C module (MD_SampleLoad() & 
  8. MD_SampleUnLoad()) so if you want to use MLOADER without using MDRIVER you'll 
  9. have to define those two routines yourself. (see MIKCVT.C as an example on 
  10. how to do that).
  11.  
  12. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  13.  
  14. General information:
  15.  
  16. When you're making a modplayer that has to support several different formats
  17. the best thing to do is to create your own internal module-format. In 
  18. MikMod's case this is the 'UNI' format. The loader module takes care of
  19. loading any of the known module formats and converting it into a UNI format.
  20.                                           
  21.             ⁄ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒ¬ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒø
  22.             ≥LOADER BLACKBOX≥                             ≥
  23.             √ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒŸ                             ≥
  24.             ≥    ⁄ƒƒƒƒƒƒƒƒƒƒø                             ≥
  25.             ≥ ⁄ƒƒ¥mod loader√ƒƒø                          ≥
  26.             ≥ ≥  ¿ƒƒƒƒƒƒƒƒƒƒŸ  ≥                          ≥
  27.             ≥ ≥  ⁄ƒƒƒƒƒƒƒƒƒƒø  ≥                          ≥
  28.             ≥ √ƒƒ¥ult loader√ƒƒ¥                          ≥
  29.             ≥ ≥  ¿ƒƒƒƒƒƒƒƒƒƒŸ  ≥                          ≥
  30.             ≥ ≥  ⁄ƒƒƒƒƒƒƒƒƒƒø  ≥                          ≥
  31.             ≥ …ÕÕ¥s3m loader√ÕÕª <- appropriate loader    ≥
  32.             ≥ ∫  ¿ƒƒƒƒƒƒƒƒƒƒŸ  ∫    for this file         ≥
  33.             ≥ ∫  ⁄ƒƒƒƒƒƒƒƒƒƒø  ∫                          ≥
  34.             ≥ ∫ƒƒ¥uni loader√ƒƒ∫                          ≥
  35.             ≥ ∫  ¿ƒƒƒƒƒƒƒƒƒƒŸ  ∫                          ≥
  36.             ≥ ∫  ⁄ƒƒƒƒƒƒƒƒƒƒø  ∫                          ≥
  37.             ≥ ∫ƒƒ¥mtm loader√ƒƒ∫                          ≥
  38.             ≥ ∫  ¿ƒƒƒƒƒƒƒƒƒƒŸ  ∫                          ≥
  39.             ≥ ∫  ⁄ƒƒƒƒƒƒƒƒƒƒø  ∫  ⁄ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒø ≥
  40.  modfile >ÕÕÕÕºƒƒ¥med loader√ƒƒ»ÕÕ¥LOADER GLUE FUNCTIONS√ƒ≈ƒƒ>>ƒ unimod *
  41.             ≥ ≥  ¿ƒƒƒƒƒƒƒƒƒƒŸ  ≥  ¿ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒŸ ≥
  42.             ≥ ≥  ⁄ƒƒƒƒƒƒƒƒƒƒø  ≥                          ≥
  43.             ≥ √ƒƒ¥xm  loader√ƒƒ¥                          ≥
  44.             ≥ ≥  ¿ƒƒƒƒƒƒƒƒƒƒŸ  ≥                          ≥
  45.             ≥ ≥  ⁄ƒƒƒƒƒƒƒƒƒƒø  ≥                          ≥
  46.             ≥ √ƒƒ¥669 loader√ƒƒ¥    - common loader       ≥
  47.             ≥ ≥  ¿ƒƒƒƒƒƒƒƒƒƒŸ  ≥      routines            ≥
  48.             ≥ ≥  ⁄ƒƒƒƒƒƒƒƒƒƒø  ≥                          ≥
  49.             ≥ √ƒƒ¥far loader√ƒƒ¥    - common loader       ≥
  50.             ≥ ≥  ¿ƒƒƒƒƒƒƒƒƒƒŸ  ≥      variables           ≥
  51.             ≥ ≥  ⁄ƒƒƒƒƒƒƒƒƒƒø  ≥                          ≥
  52.             ≥ √ƒƒ¥dsm loader√ƒƒ¥                          ≥
  53.             ≥ ≥  ¿ƒƒƒƒƒƒƒƒƒƒŸ  ≥                          ≥
  54.             ≥ ≥  ⁄ƒƒƒƒƒƒƒƒƒƒø  ≥                          ≥
  55.             ≥ ¿ƒƒ¥... loader√ƒƒŸ                          ≥
  56.             ≥    ¿ƒƒƒƒƒƒƒƒƒƒŸ                             ≥
  57.             ≥                                             ≥
  58.             ¿ƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒƒŸ
  59.             
  60. To prevent having to link _all_ loaders to the loader module when you only 
  61. wanted to use the uni-loader, for example), the first thing the main module 
  62. has to do before using the loader module is to 'register' all loaders it 
  63. might need. This way only the registered drivers will get linked to the 
  64. executable.
  65.     
  66. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  67.  
  68. void ML_RegisterLoader(LOADER *ldr)
  69. ===================================
  70.  
  71. Input parms:
  72.  
  73.     ldr     pointer to a LOADER structure
  74.  
  75.  
  76. Returns:
  77.  
  78.     -
  79.  
  80.  
  81. Description:
  82.  
  83. Before you can load any modules (with ML_LoadFN() or ML_LoadFP()) you first 
  84. have to register the loaders you want to use. This way only the registered 
  85. loaders are linked to the resulting program, so if you only wanted to support 
  86. a single format your program won't be so big.
  87.  
  88.  
  89. Example:
  90.  
  91.     [ at the start of the main program: ]
  92.  
  93.     {
  94.         ...
  95.  
  96.         ML_RegisterLoader(&modload);
  97.         ML_RegisterLoader(&uniload);
  98.  
  99.         ML_InfoLoader();
  100.         ...
  101.         ...
  102.  
  103.     }
  104.  
  105. (if you want to keep your program as small as possible, only use the .UNI 
  106. loader since it is the smallest loader available (go figure!) )
  107.  
  108. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  109.  
  110. void ML_InfoLoader(void)
  111. ========================
  112.  
  113. Input parms:
  114.  
  115.     -
  116.  
  117.  
  118. Returns:
  119.  
  120.     -
  121.  
  122.  
  123. Description:
  124.  
  125. This function produces a list of all registered loader modules to stdout. Use 
  126. it _after_ you've registered all loaders using ML_RegisterLoader().
  127.  
  128. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  129.  
  130. UNIMOD *ML_LoadFP(FILE *fp)
  131. ===========================
  132.  
  133. Input parms:
  134.  
  135.     fp    filepointer to a music module
  136.  
  137.  
  138. Returns:
  139.  
  140.     A pointer to a UNIMOD structure
  141.  
  142.     or
  143.  
  144.     NULL if an error occured during loading.
  145.  
  146.  
  147. Description:
  148.  
  149. With this routine you can load a music-module by it's file-pointer. If it 
  150. returns NULL, print myerr (MMIO.C) to see what went wrong. This routine 
  151. doesn't close the filepointer when it's done, but you can't rely on it still 
  152. having the same file-position. Use ML_Free() to free the UNIMOD when you're 
  153. done with it.
  154.  
  155. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  156.  
  157. void ML_Free(UNIMOD *mf)
  158. ========================
  159.  
  160. Input parms:
  161.  
  162.     mf    pointer to a UNIMOD structure
  163.  
  164.  
  165. Returns:
  166.  
  167.     -
  168.  
  169.  
  170. Description:
  171.  
  172. Use this routine to free the module you loaded with ML_LoadFN() or 
  173. ML_LoadFP().
  174.  
  175. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  176.  
  177. UNIMOD *ML_LoadFN(char *filename)
  178. =================================
  179.  
  180. Input parms:
  181.  
  182.     filename        The filename of the module you want to load.
  183.  
  184.  
  185. Returns:
  186.  
  187.     A pointer to a UNIMOD structure
  188.  
  189.     or
  190.  
  191.     NULL if an error occured during loading.
  192.  
  193.  
  194. Description:
  195.  
  196. With this routine you can load a music-module by it's filename. If it returns 
  197. NULL, print myerr (MERROR.C) to see what went wrong. Use ML_Free() to free 
  198. the UNIMOD when you're done with it.
  199.  
  200. ÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕÕ
  201.